Sdf File Definition

Introduction

The syntax file (SDF) is the heart of syntax specific capabilities of Twistpad.
All SDF files are located in the sub-folder "Syntax" of the main Twistpad folder.
It's the SDF files which define how a syntax is applied to a particular file (identified by it's extension)

The syntax of the SDF file is very similar to a standard Windows INI file. If you are familiar with this type of file, it should be easier to edit SDF files.
Although a very complex file syntax can be archived in Twistpad, the ease of creation of a new syntax it's one of the many strengths you can find in Twistpad. In 2 minutes you can create a new syntax file, simply based on keywords.
There are 3 main blocks in a SDF file, the [::Header::] which can be only one, and is not optional, and several sets of optional keywords and start-stop sections.

Header section

The header section is required to proper enable syntax for a specific file type in Twistpad.
The header is always : [::Header::]
The keywords for the Header section are:

SyntaxName*: The name of the syntax
Extensions*: The file extensions where this syntax is applied
Functions: Regular expression to define functions or sections
FunctionSubs: Regular expression to retrieve RE groups (between brackets). If ommited the full line context will be displayed
HelpFile: One or more Help files for use with this syntax (multiple can be used with the | sign)
Spelling: 1 or 0. When 0, means spell nothing, except in the contexts defined in the SpellingContexts keyword, if 1 spell everything except in the contexts defined in the SpellingContexts keyword**
SpellingContexts: Coma delimited contexts, it's use is defined in the Spelling keyword
SnippetFile: Snippet file to use in the syntax
Delimiters: custom delimiters for this syntax (please note a spaces and tabs are always considered delimiters)
CommentChar: Character (or a multiple characters) to be used in comment/uncomment commands
CommentCharEnd: Character (or a multiple characters) to be used in comment/uncomment commands. If CommentCharEnd is omitted, comments will be applied on a line by line basis (using the character defined in CommentChar)
Template: A path to a file that will be inserted when the new command is executed for this file type (if the complete path is not given Twistpad will look in both template folder's)
KeywordsSeparator: Define which is the character that will be used as the separator for syntax files (if omitted ; will be used)
Brackets: Define which characters are considered brackets. Only the start bracket of the choices: "({<[" is required. Default value are the the 4 brackets.

Sections

There are two types of sections, Start-Stop Sections and Keywords Section.
Start-Stop Sections define a text color/format for, as the name implies, a block of text with recognized tokens. for instance you could say you want everything that starts with { and ends with } in blue.
Keywords define a single word which is to be colored, for instance, you might want that the word "Blue" appears in blue.
Both have the following Keywords:

Type*: StartStop or Keyword
Context*: a unique number that identifies this StartStop ID
Scope*: Defines a context where this context is active
Priority*: or importance of this keyword/StartStop, higher numbers means higher priority in displaying the context
WholeWordOnly*: 1 or 0, if 1 the word separator has to be one of the delimiters, if not the word separators are ignored
CaseSensitive:1 or 0, Denotes if the StartStop Keys or the Keywords should be treated as case sensitive (1) or not (0)
BeginParagraph:1 or 0, Denotes if the StartStop Keys or the Keywords should be only activated if they are the first word in a paragraph
StartOfParagraph:1 or 0, Denotes if the StartStop Keys or the Keywords should be only activated if they start at the beginning of a paragraph
Background*:Color of the background, in HEX style (use insert color) or Default for default background color
Foreground*:Color of the foreground, in HEX style (use insert color) or Default for default foreground color
Bold:0 or 1, to make words in bold
Italic:0 or 1, to make words in italic

Specific StartStop Keywords

First: The first word to define the start section
Last: The last word to define the stop section
Outline: 0 or 1, defines whether this section can be closed
Smart: 0 or 1, defines if the stop section is incremented, for example to find a matching pair of { when smart is enabled, any closing sections are ignored if more open sections are found
EscapeChar: Defines the character used to cancel a start or stop section

Specific Keywords Keywords

Keyword1 to Keyword16: The keywords are defined here, separated by a ; or the separator defined in the ::header:: section
(eg. Keyword1=key1;key2;key3;key4)

Example

As a simple example let's say that you wish to have the words Twistpad, Syntax and File in blue.
Also everything between { and } in bold red. And as a final touch in our example let's define the word Color to be displayed in green only when it's between { and }.
Point to new file in Twistpad, create the header that should be something like:

[::Header::]
SyntaxName=Test syntax
extensions=tst

Now, as a rule, although this is not required, you should declare the start stop sections first. So we need to declare the brackets section

[Brackets]
Type=StartStop
Context=1
Scope=0
Priority=7
First={
Last=}
Background=Default
Foreground=FF0000
Bold=1

Now on to the keywords:

[BlueKeywords]
Type=keyword
Context=100
Scope=0
Priority=6
WholeWordOnly=1
Keyword1=Twistpad;Syntax;File
Background=Default
Foreground=0000FF

[GreenColorOnBrackets]
Type=keyword
Context=101
Scope=1
Priority=6
WholeWordOnly=1
Keyword1=Color
Background=Default
Foreground=008000

Notice the scope set to 1 on [GreenColorOnBrackets], this is to force the use of this style only in context 1 (between brackets)

Save the file as Test.sdf on the Syntax sub-folder of Twistpad and open a file with the tst extension to test the syntax just created.

Tips

The best way to make a new syntax is to modify an existing one, you can find all syntax definition files used by Twistpad in the sub folder "Syntax" in the "All Users Application Data" folder (Or double click the syntax screen on the Twistpad preferences dialogue).
In the Carthago Software Site, you may find more syntax files, the chances are you will not need to create any SDF file, as someone might already created it!

Notes

* Denotes a required keyword
** Context's are explained in the StartStop and Keywords section